officeparser 7.2.3 → 7.3.0

package/README.md

@@ -2,9 +2,9 @@
 
 A robust, strictly-typed **Node.js and Browser** library for parsing office files into a rich **Abstract Syntax Tree (AST)** and generating high-fidelity output in multiple formats.
 
-**Parses:** [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`odt`](https://en.wikipedia.org/wiki/OpenDocument) · [`odp`](https://en.wikipedia.org/wiki/OpenDocument) · [`ods`](https://en.wikipedia.org/wiki/OpenDocument) · [`pdf`](https://en.wikipedia.org/wiki/PDF) · [`rtf`](https://en.wikipedia.org/wiki/Rich_Text_Format) · [`csv`](https://en.wikipedia.org/wiki/Comma-separated_values) · [`md`](https://en.wikipedia.org/wiki/Markdown) · [`html`](https://en.wikipedia.org/wiki/HTML)
+**Parses:** [`docx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`pptx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`xlsx`](https://en.wikipedia.org/wiki/Office_Open_XML) · [`odt`](https://en.wikipedia.org/wiki/OpenDocument) · [`odp`](https://en.wikipedia.org/wiki/OpenDocument) · [`ods`](https://en.wikipedia.org/wiki/OpenDocument) · [`pdf`](https://en.wikipedia.org/wiki/PDF) · [`rtf`](https://en.wikipedia.org/wiki/Rich_Text_Format) · [`csv`](https://en.wikipedia.org/wiki/Comma-separated_values) · [`md`](https://en.wikipedia.org/wiki/Markdown) · [`html`](https://en.wikipedia.org/wiki/HTML) · [`epub`](https://en.wikipedia.org/wiki/EPUB)
 
-**Generates:** `Markdown` · `HTML` · `CSV` · `RTF` · `PDF` · `Plain Text` · `RAG Chunks`
+**Generates:** `Markdown` · `HTML` · `CSV` · `RTF` · `PDF` · `EPUB` · `Plain Text` · `RAG Chunks`
 
 [![npm version](https://badge.fury.io/js/officeparser.svg)](https://badge.fury.io/js/officeparser)
 [![Total Downloads](https://img.shields.io/npm/dt/officeparser.svg)](https://www.npmjs.com/package/officeparser)
@@ -42,6 +42,8 @@ A robust, strictly-typed **Node.js and Browser** library for parsing office file
 - [Native RAG Chunking](#native-rag-chunking)
 - [The AST Structure](#the-ast-structure)
 - [Deep Dive: Document Components](#deep-dive-document-components)
+- [Markdown Dialect Support](#markdown-dialect-support)
+- [EPUB Support](#epub-support)
 - [Performance Highlights](#performance-highlights)
 - [Advanced AST Usage](#advanced-ast-usage)
 - [Configuration Reference](#configuration-reference)
@@ -93,6 +95,9 @@ npx officeparser data.xlsx --to=csv --csvDelimiter=";"
 # Generate RAG chunks
 npx officeparser document.pdf --to=chunks
 
+# Convert DOCX to EPUB (--extractAttachments is required to embed images)
+npx officeparser book.docx --extractAttachments --to=epub --output=book.epub
+
 # Overriding file extension mapping
 npx officeparser my_document --fileType=docx --to=json
 ```
@@ -106,9 +111,9 @@ npx officeparser my_document --fileType=docx --to=json
 
 | Flag | Values | Default | Description |
 |------|--------|---------|-------------|
-| `--to` | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | Output format |
+| `--to` | `json\|text\|md\|html\|csv\|rtf\|pdf\|epub\|chunks` | `json` | Output format |
 | `--output` | path | — | Write output to a file |
-| `--fileType` | `docx\|xlsx\|pptx\|odt\|odp\|ods\|pdf\|rtf\|csv\|md\|html` | — | Explicitly override input file type detection |
+| `--fileType` | `docx\|xlsx\|pptx\|odt\|odp\|ods\|pdf\|rtf\|csv\|md\|html\|epub` | — | Explicitly override input file type detection |
 | `--ocr` | boolean | `false` | Enable OCR for images |
 | `--extractAttachments` | boolean | `false` | Extract images/charts as Base64 |
 | `--ignoreNotes` | boolean | `false` | Ignore footnotes/endnotes/speaker notes |
@@ -126,7 +131,7 @@ npx officeparser my_document --fileType=docx --to=json
 | `--includeFormatting` | boolean | `true` | Include formatting style map matching |
 | `--renderMetadata` | boolean | `false` | Render metadata as visible content in the generated output |
 | `--htmlConfig.containerWidth` | string \| number | `auto` | HTML output container width (e.g. `900px`, `100%`) |
-| ~~`--format`~~ | `json\|text\|md\|html\|csv\|rtf\|pdf\|chunks` | `json` | **Deprecated.** Use `--to` |
+| ~~`--format`~~ | `json\|text\|md\|html\|csv\|rtf\|pdf\|epub\|chunks` | `json` | **Deprecated.** Use `--to` |
 | ~~`--toText`~~ | `true\|false` | `false` | **Deprecated.** Use `--to=text` |
 | ~~`--ocrLanguage`~~ | string | `eng` | **Deprecated.** Use `--ocrConfig.language` |
 | ~~`--putNotesAtLast`~~ | `true\|false` | `false` | **Deprecated and ignored.** Notes are attached structurally to their nodes. |
@@ -306,13 +311,16 @@ const { value: html } = await OfficeGenerator.generate(ast, 'html', {
 const { value: csv } = await OfficeGenerator.generate(ast, 'csv');
 ```
 
-**Supported destinations:** `'text'` · `'md'` · `'html'` · `'csv'` · `'rtf'` · `'pdf'` · `'chunks'`
+**Supported destinations:** `'text'` · `'md'` · `'html'` · `'csv'` · `'rtf'` · `'pdf'` · `'epub'` · `'chunks'`
 
 > [!NOTE]
 > **PDF generation** requires the optional `puppeteer` peer dependency:
 > ```bash
 > npm install puppeteer
 > ```
+>
+> **EPUB generation with images** requires `extractAttachments: true` on the parse step that
+> produced the AST — see [EPUB Support](#epub-support).
 
 ---
 
@@ -440,10 +448,10 @@ interface OfficeChunk {
 
 ```text
 OfficeParserAST
-├── type: 'docx' | 'pdf' | 'xlsx' | 'csv' | 'md' | ...  (11 formats)
+├── type: 'docx' | 'pdf' | 'xlsx' | 'csv' | 'md' | 'epub' | ...  (12 formats)
 ├── metadata: { author, title, created, modified, keywords, customProperties, nativeProperties, styleMap, ... }
 ├── content: [ OfficeContentNode ]
-│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | 'comment' | ...
+│   ├── type: 'paragraph' | 'heading' | 'table' | 'list' | 'image' | 'chart' | 'comment' | 'admonition' | 'embed' | 'definitionList' | ...
 │   ├── text: string  (concatenated text of node + all descendants)
 │   ├── children: [ OfficeContentNode ]  (recursive structural children)
 │   ├── notes: [ OfficeContentNode ]     (footnotes/endnotes/slide notes attached to this node)
@@ -596,6 +604,94 @@ console.log(ast.metadata.nativeProperties);
 // PDF:  { Title: 'Report', XMP: { ... } }
 ```
 
+### 8. Admonitions, Embeds & Definition Lists
+
+```text
+Admonition Node (type: 'admonition')
+├── metadata: { admonitionType: 'note' | 'tip' | 'important' | 'warning' | 'caution', title?: string }
+└── children: [ Paragraph | List | ... ]   (block content)
+
+Embed Node (type: 'embed')
+└── metadata: { embedType: 'youtube', videoId: string, url?: string, width?: string, align?: string }
+
+Definition List Node (type: 'definitionList')
+└── children:
+    ├── Definition Term (type: 'definitionTerm')
+    └── Definition Description (type: 'definitionDescription')
+```
+
+- `admonition` round-trips through both Markdown (`> [!NOTE]` / `:::note ... :::`) and HTML (`<div class="admonition admonition-note" data-type="note">`)
+- `embed` currently models YouTube videos; HTML round-trips via `<div data-youtube-video="ID">`, Markdown falls back to a raw HTML block or a plain link
+- Abbreviations (`*[HTML]: Hypertext Markup Language`) are stored as `TextMetadata.abbreviationTitle` on the abbreviated text node rather than as a separate node type
+
+---
+
+## Markdown Dialect Support
+
+Beyond CommonMark/GFM basics, `MarkdownParser`/`MarkdownGenerator` support an extended dialect aimed at
+full-fidelity round-tripping with rich Markdown editors. Every construct below parses to a first-class
+AST node/metadata field and regenerates back to the canonical syntax shown, so `.md → AST → .md` is
+idempotent and `.md → AST → HTML → AST → .md` survives unchanged.
+
+| Feature | Markdown syntax | AST representation |
+|---|---|---|
+| Task lists (GFM) | `- [x] Done` / `- [ ] Todo` | `ListMetadata.isTask` / `.checked` |
+| Admonitions | `> [!NOTE]` (also accepts GLFM `:::note ... :::` on import) | `type: 'admonition'`, `AdmonitionMetadata` |
+| Footnotes | `Text[^1]` + `[^1]: Definition` | `type: 'note'`, keyed by footnote id |
+| Definition lists | `Term\n: Definition` | `type: 'definitionList'` / `'definitionTerm'` / `'definitionDescription'` |
+| Abbreviations | `*[HTML]: Hypertext Markup Language` | `TextMetadata.abbreviationTitle` |
+| Attribute lists | `![alt](img.png){width=50% .centered}` | `ImageMetadata.width` / `.align`, `TableMetadata.align` |
+| Citations | `[@smith2024]` | `TextMetadata.citationKey` |
+| Wikilinks | `[[Page]]` / `[[Page\|Alias]]` | `TextMetadata.wikilink`, `.link`, `.linkType` |
+| Inline/block math | `$E=mc^2$` / `` $$...$$ `` | `TextMetadata.math` (`'inline' \| 'block'`) |
+| Frontmatter arrays | `tags: [a, b]` or `tags: ["a","b"]` | Real array in `metadata.customProperties`/`nativeProperties` |
+| MDX components (import-only) | `<Component prop="x">...</Component>` | Stripped; inner Markdown is kept. Never generated back. |
+
+> [!NOTE]
+> MDX/JSX stripping is one-directional (parse-only) — officeParser never authors JSX back into Markdown.
+> Wikilink enable/disable and citekey→bibliography resolution are application-level concerns; officeParser
+> always parses/generates the syntax itself.
+
+The same round-trip fidelity extends to HTML, so content saved from a rich-text editor survives a
+save→reload cycle:
+
+| HTML attribute | AST field | Notes |
+|---|---|---|
+| `data-width` / `data-align` / inline `style="width:…"` on `<img>` | `ImageMetadata.width` / `.align` | |
+| `data-align` on `<table>` | `TableMetadata.align` | |
+| `colspan` / `rowspan` on `<td>`/`<th>` | `CellMetadata.colSpan` / `.rowSpan` | Previously dropped on HTML import — merged cells now survive a save→reload cycle |
+| `<div data-youtube-video="ID">` / `<iframe src="...youtube.com...">` | `type: 'embed'` | |
+| `<ul data-type="taskList">` / `<li data-checked>` | `ListMetadata.isTask` / `.checked` | |
+
+---
+
+## EPUB Support
+
+EPUB files are ZIP archives of XHTML content plus an OPF manifest — `EpubParser` unzips the archive,
+resolves the spine's reading order from `content.opf`, and parses each XHTML document through the
+existing `HtmlParser`, so EPUB content shares the same AST shape (and the same Markdown-dialect
+fidelity above) as every other format. Dublin Core metadata (`dc:title`, `dc:creator`, `dc:description`,
+`dc:subject`, `dc:date`, `dc:publisher`, `dc:language`, `dc:identifier`) maps into `ast.metadata` /
+`ast.metadata.nativeProperties`, and cover art is exposed via `metadata.customProperties.coverImageName`.
+
+`EpubGenerator` renders the AST through `HtmlGenerator` and packages the result as a minimal, valid
+EPUB 3 (`mimetype`, `META-INF/container.xml`, an OPF manifest, a nav document, and one XHTML chapter).
+
+> [!IMPORTANT]
+> **Pass `extractAttachments: true` when converting to or from EPUB if the document has images.**
+> Without it, the parser never pulls embedded image bytes out of the source document, so there is
+> nothing for the EPUB generator to package — images silently disappear even though everything else
+> converts correctly. Images are packaged as real zip entries (`OEBPS/images/...`) declared in the OPF
+> manifest, not `data:` URIs — most EPUB reading systems do not render `data:` URIs in image `src`.
+>
+> This only matters for the two-step `OfficeParser.parseOffice()` → `OfficeGenerator.generate()` API
+> and the CLI. [`OfficeConverter.convert()`](#officeconverter-one-step-api) enables `extractAttachments`
+> automatically unless you explicitly set `generatorConfig.includeImages: false`.
+>
+> ```bash
+> npx officeparser book.docx --extractAttachments --to=epub --output=book.epub
+> ```
+
 ---
 
 ## Performance Highlights
@@ -852,7 +948,7 @@ Pass as `htmlConfig` inside `GeneratorConfig`.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `standalone` | `boolean` | `true` | Wrap output in a full `<html>` document with CSS |
+| `standalone` | `boolean \| StandaloneConfig` | `true` | Controls the HTML "document envelope" — see below |
 | `chartJsSrc` | `string` | jsDelivr CDN | URL for the Chart.js library |
 | `containerWidth` | `string \| number` | `'auto'` | Max width of the content container. Positive number (px), CSS length string (`'900px'`, `'100%'`, `'60vw'`), or `'auto'`. Invalid values fall back to `'auto'` with an `INVALID_CONTAINER_WIDTH` warning |
 | `customCss` | `string` | `''` | Raw CSS injected into the `<style>` block; use this to override built-in styles |
@@ -861,6 +957,49 @@ Pass as `htmlConfig` inside `GeneratorConfig`.
 | `injections.bodyStart` | `string` | `''` | Raw HTML injected after `<body>` |
 | `injections.bodyEnd` | `string` | `''` | Raw HTML injected before `</body>` |
 
+#### `standalone`: granular envelope control
+
+`standalone` conflates several independent decisions: whether to emit the `<!doctype>/<html>/<head>/
+<body>` shell, how CSS is delivered, and whether to inject scripts/meta tags/injections. The boolean
+shorthand still works — **`true`/omitted turns every part on** (a complete document); **`false` turns
+every part off** (a bare content fragment, safe to drop into a page you don't control). Pass an
+object instead for granular control; any field you omit defaults to its "on" (standalone) value:
+
+| `StandaloneConfig` field | Type | Default | Description |
+|--------|------|---------|-------------|
+| `document` | `boolean` | `true` | Wrap in `<!DOCTYPE html><html><head>…</head><body>…</body></html>` |
+| `metaTags` | `boolean` | `true` | Emit `<title>`/`<meta>` tags. Only meaningful when `document` is true |
+| `styles` | `'full' \| 'scoped' \| 'none'` | `'full'` | See below |
+| `scripts` | `boolean` | `true` | Emit the Chart.js CDN loader and spreadsheet-interactivity `<script>` tags |
+| `headInjections` | `boolean` | `true` | Apply `injections.headStart`/`headEnd`. Only meaningful when `document` is true |
+| `bodyInjections` | `boolean` | `true` | Apply `injections.bodyStart`/`bodyEnd` — applies even to a bare fragment |
+
+`styles` controls how the built-in stylesheet is delivered:
+- **`'full'`** — the complete stylesheet using global selectors (`body`, `h1`, `table`, …). This is
+  what `standalone: true` has always emitted.
+- **`'scoped'`** — the same styling, scoped under the fragment's own wrapper via CSS `@scope` so it
+  cannot leak onto a host page's elements. Requires a modern engine (Chrome 118+, Safari 17.4+,
+  Firefox 128+); for universal support use `'none'` (bring your own CSS) or `'full'`.
+- **`'none'`** — no stylesheet at all; the host page (or rich-text editor, or EPUB reader) supplies
+  its own styling.
+
+```js
+// A styled fragment to embed in your own page, without a document shell:
+await ast.to('html', { htmlConfig: { standalone: { document: false } } });
+
+// The same, but with styles scoped so they can't leak onto your page's own elements:
+await ast.to('html', { htmlConfig: { standalone: { document: false, styles: 'scoped' } } });
+
+// A completely bare fragment (no shell, no styles, no scripts) — e.g. for a rich-text editor:
+await ast.to('html', { htmlConfig: { standalone: false } });
+```
+
+> [!NOTE]
+> **Behavior change from `standalone: false`:** previously this emitted a fragment with a *global,
+> unscoped* `<style>` block. It now emits a genuinely bare fragment (no `<style>` at all), matching
+> "every part off." If you relied on the old styled-fragment behavior, pass
+> `{ document: false }` (or `{ document: false, styles: 'full' }`) instead.
+
 ### MdGeneratorConfig
 
 Pass as `mdConfig` inside `GeneratorConfig`.

package/dist/OfficeGenerator.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfficeGenerator = void 0;
 const ChunkingGenerator_js_1 = require("./generators/ChunkingGenerator.js");
 const CsvGenerator_js_1 = require("./generators/CsvGenerator.js");
+const EpubGenerator_js_1 = require("./generators/EpubGenerator.js");
 const HtmlGenerator_js_1 = require("./generators/HtmlGenerator.js");
 const MarkdownGenerator_js_1 = require("./generators/MarkdownGenerator.js");
 const PdfGenerator_js_1 = require("./generators/PdfGenerator.js");
@@ -60,6 +61,9 @@ class OfficeGenerator {
             case 'chunks':
                 generator = new ChunkingGenerator_js_1.ChunkingGenerator(ast, config);
                 break;
+            case 'epub':
+                generator = new EpubGenerator_js_1.EpubGenerator(ast, config);
+                break;
             default:
                 throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.FORMAT_UNSUPPORTED, undefined, destination);
         }

package/dist/OfficeParser.d.ts

@@ -14,6 +14,7 @@
  * - CSV (Comma-Separated Values)
  * - MD (Markdown)
  * - HTML (HyperText Markup Language)
+ * - EPUB (E-book format)
  *
  * **Usage:**
  * ```typescript
@@ -66,6 +67,7 @@ export declare class OfficeParser {
      * - `.csv` → CsvParser
      * - `.md` → MarkdownParser
      * - `.html` → HtmlParser
+     * - `.epub` → EpubParser
      *
      * @param file - File path (string), Buffer, or ArrayBuffer containing the document
      * @param config - Optional configuration object (defaults applied for all omitted options)

package/dist/OfficeParser.js

@@ -15,6 +15,7 @@
  * - CSV (Comma-Separated Values)
  * - MD (Markdown)
  * - HTML (HyperText Markup Language)
+ * - EPUB (E-book format)
  *
  * **Usage:**
  * ```typescript
@@ -39,6 +40,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OfficeParser = void 0;
 const CsvParser_js_1 = require("./parsers/CsvParser.js");
+const EpubParser_js_1 = require("./parsers/EpubParser.js");
 const ExcelParser_js_1 = require("./parsers/ExcelParser.js");
 const HtmlParser_js_1 = require("./parsers/HtmlParser.js");
 const MarkdownParser_js_1 = require("./parsers/MarkdownParser.js");
@@ -83,6 +85,7 @@ class OfficeParser {
      * - `.csv` → CsvParser
      * - `.md` → MarkdownParser
      * - `.html` → HtmlParser
+     * - `.epub` → EpubParser
      *
      * @param file - File path (string), Buffer, or ArrayBuffer containing the document
      * @param config - Optional configuration object (defaults applied for all omitted options)
@@ -232,6 +235,9 @@ class OfficeParser {
                 case 'md':
                     result = await (0, MarkdownParser_js_1.parseMarkdown)(buffer, internalConfig);
                     break;
+                case 'epub':
+                    result = await (0, EpubParser_js_1.parseEpub)(buffer, internalConfig);
+                    break;
                 default:
                     throw (0, errorUtils_js_1.getOfficeError)(types_js_1.OfficeErrorType.EXTENSION_UNSUPPORTED, internalConfig, ext);
             }

package/dist/cli.d.ts

@@ -8,7 +8,7 @@
  *   officeparser file.docx --ocr --extractAttachments
  *
  * Options (--key=value, --key value, or bare flags):
- *   --to=json|text|md|html|csv|rtf|pdf|chunks  Convert AST to specified format (default: json)
+ *   --to=json|text|md|html|csv|rtf|pdf|epub|chunks  Convert AST to specified format (default: json)
  *   --output=path             Save result to a file
  *   --fileType=docx|xlsx|...  Override file type detection
  *   --ocr                     Enable OCR for images (default: false)

package/dist/cli.js

@@ -9,7 +9,7 @@
  *   officeparser file.docx --ocr --extractAttachments
  *
  * Options (--key=value, --key value, or bare flags):
- *   --to=json|text|md|html|csv|rtf|pdf|chunks  Convert AST to specified format (default: json)
+ *   --to=json|text|md|html|csv|rtf|pdf|epub|chunks  Convert AST to specified format (default: json)
  *   --output=path             Save result to a file
  *   --fileType=docx|xlsx|...  Override file type detection
  *   --ocr                     Enable OCR for images (default: false)
@@ -333,7 +333,7 @@ else {
     console.log('Usage: officeparser <file> [options]');
     console.log('');
     console.log('Options:');
-    console.log('  --to=json|text|md|html|pdf|csv|rtf|chunks   Target conversion format (default: json)');
+    console.log('  --to=json|text|md|html|pdf|csv|rtf|epub|chunks  Target conversion format (default: json)');
     console.log('  --output=file.ext                           Save output to file instead of stdout');
     console.log('  --fileType=docx|xlsx|pptx|odt|...           Explicitly override input file type detection');
     console.log('  --ocr                                       Enable OCR for images (default: false)');
@@ -371,5 +371,6 @@ else {
     console.log('  officeparser document.docx --to md');
     console.log('  officeparser report.pdf --ocr --ocrConfig.language eng --to text');
     console.log('  officeparser data.xlsx --to csv --output data.csv --csvDelimiter ";"');
+    console.log('  officeparser document.docx --extractAttachments --to epub --output document.epub');
     console.log('  officeparser image_doc --fileType docx --to json');
 }

package/dist/generators/BaseGenerator.d.ts

@@ -48,6 +48,17 @@ export declare abstract class BaseGenerator<D extends UniversalGeneratorFormat =
      * Helper to generate a unique ID (slug) from text.
      */
     protected slugify(text: string): string;
+    private noteFootnoteKeys;
+    private usedFootnoteKeys;
+    private footnoteKeyCounter;
+    /**
+     * Assigns a stable, unique reference key to a footnote/endnote node, reused for both
+     * its inline reference marker and its collected definition. Source ids aren't reliably
+     * unique across a document - DOCX/ODT number footnotes and endnotes in separate
+     * sequences, so both can carry noteId "1" - so a source id is only reused when it
+     * hasn't already been claimed; otherwise a sequential counter guarantees uniqueness.
+     */
+    protected getFootnoteKey(note: OfficeContentNode): string;
     /**
      * Recursively extracts plain text from a node and its children.
      */

package/dist/generators/BaseGenerator.js

@@ -89,6 +89,35 @@ class BaseGenerator {
             .replace(/[\s_-]+/g, '-')
             .replace(/^-+|-+$/g, '');
     }
+    noteFootnoteKeys = new Map();
+    usedFootnoteKeys = new Set();
+    footnoteKeyCounter = 0;
+    /**
+     * Assigns a stable, unique reference key to a footnote/endnote node, reused for both
+     * its inline reference marker and its collected definition. Source ids aren't reliably
+     * unique across a document - DOCX/ODT number footnotes and endnotes in separate
+     * sequences, so both can carry noteId "1" - so a source id is only reused when it
+     * hasn't already been claimed; otherwise a sequential counter guarantees uniqueness.
+     */
+    getFootnoteKey(note) {
+        const cached = this.noteFootnoteKeys.get(note);
+        if (cached)
+            return cached;
+        const preferred = note.metadata?.noteId;
+        let key;
+        if (preferred && !this.usedFootnoteKeys.has(preferred)) {
+            key = preferred;
+        }
+        else {
+            do {
+                this.footnoteKeyCounter++;
+                key = String(this.footnoteKeyCounter);
+            } while (this.usedFootnoteKeys.has(key));
+        }
+        this.usedFootnoteKeys.add(key);
+        this.noteFootnoteKeys.set(note, key);
+        return key;
+    }
     /**
      * Recursively extracts plain text from a node and its children.
      */

package/dist/generators/CsvGenerator.d.ts

@@ -20,9 +20,17 @@ export declare class CsvGenerator extends BaseGenerator<'csv'> {
      */
     private renderNodeToRows;
     /**
-     * Escapes a value for CSV formatting.
+     * Escapes a value for CSV formatting: RFC 4180 quoting plus a spreadsheet
+     * formula-injection guard (see csvSafeCell in ../utils/sanitize.js).
      */
     private escapeCsvValue;
+    /** Sanitizes a value for a `#` comment line (document metadata or sheet name).
+     *  Comment lines are free text prefixed with `#`, not RFC-4180 cells, so they
+     *  can't be quoted; instead we (a) collapse newlines so the value can't break out
+     *  and inject a new row, and (b) replace the column delimiter with a space so a
+     *  value like `x,=1+1` can't split into a second cell that a spreadsheet would
+     *  evaluate as a formula (CSV formula/DDE injection). */
+    private sanitizeComment;
     /**
      * Renders metadata as comments.
      */

package/dist/generators/CsvGenerator.js

@@ -4,6 +4,7 @@ exports.CsvGenerator = void 0;
 const fflate_1 = require("fflate");
 const types_js_1 = require("../types.js");
 const sheetUtils_js_1 = require("../utils/sheetUtils.js");
+const sanitize_js_1 = require("../utils/sanitize.js");
 const BaseGenerator_js_1 = require("./BaseGenerator.js");
 /**
  * Generates CSV files from an AST.
@@ -26,7 +27,7 @@ class CsvGenerator extends BaseGenerator_js_1.BaseGenerator {
         if (sheetNodes.length === 0) {
             return { value: '', messages: this.messages };
         }
-        const metadataHeader = this.config.renderMetadata ? this.renderMetadata(this.ast) : '';
+        const metadataHeader = this.config.renderMetadata ? this.renderMetadata(this.ast, delimiter) : '';
         // 2. Filter sheets based on range
         let selectedNodes = sheetNodes;
         if (csvConfig.sheets) {
@@ -59,7 +60,7 @@ class CsvGenerator extends BaseGenerator_js_1.BaseGenerator {
                 mergedLines.push(metadataHeader.trim());
             for (const sheet of sheetData) {
                 if (sheetData.length > 1)
-                    mergedLines.push(`# Sheet: ${sheet.name}`);
+                    mergedLines.push(`# Sheet: ${this.sanitizeComment(sheet.name, delimiter)}`);
                 for (const row of sheet.rows) {
                     const paddedRow = [...row];
                     // Don't pad comments
@@ -197,34 +198,43 @@ class CsvGenerator extends BaseGenerator_js_1.BaseGenerator {
         return rows;
     }
     /**
-     * Escapes a value for CSV formatting.
+     * Escapes a value for CSV formatting: RFC 4180 quoting plus a spreadsheet
+     * formula-injection guard (see csvSafeCell in ../utils/sanitize.js).
      */
     escapeCsvValue(val, delimiter) {
-        const needsQuotes = val.includes(delimiter) || val.includes('"') || val.includes('\n') || val.includes('\r');
-        if (!needsQuotes)
-            return val;
-        // Double up existing quotes and wrap in quotes
-        return `"${val.replace(/"/g, '""')}"`;
+        return (0, sanitize_js_1.csvSafeCell)(val, delimiter);
+    }
+    /** Sanitizes a value for a `#` comment line (document metadata or sheet name).
+     *  Comment lines are free text prefixed with `#`, not RFC-4180 cells, so they
+     *  can't be quoted; instead we (a) collapse newlines so the value can't break out
+     *  and inject a new row, and (b) replace the column delimiter with a space so a
+     *  value like `x,=1+1` can't split into a second cell that a spreadsheet would
+     *  evaluate as a formula (CSV formula/DDE injection). */
+    sanitizeComment(val, delimiter) {
+        let s = String(val ?? '').replace(/[\r\n]+/g, ' ');
+        if (delimiter)
+            s = s.split(delimiter).join(' ');
+        return s;
     }
     /**
      * Renders metadata as comments.
      */
-    renderMetadata(ast) {
+    renderMetadata(ast, delimiter) {
         if (!ast.metadata)
             return '';
         const m = ast.metadata;
         let output = '';
         if (m.title)
-            output += `# Title: ${m.title}\n`;
+            output += `# Title: ${this.sanitizeComment(m.title, delimiter)}\n`;
         if (m.author)
-            output += `# Author: ${m.author}\n`;
+            output += `# Author: ${this.sanitizeComment(m.author, delimiter)}\n`;
         if (m.created)
-            output += `# Created: ${new Date(m.created).toLocaleString()}\n`;
+            output += `# Created: ${this.sanitizeComment(new Date(m.created).toLocaleString(), delimiter)}\n`;
         if (m.modified)
-            output += `# Modified: ${new Date(m.modified).toLocaleString()}\n`;
+            output += `# Modified: ${this.sanitizeComment(new Date(m.modified).toLocaleString(), delimiter)}\n`;
         if (m.customProperties) {
             for (const [k, v] of Object.entries(m.customProperties)) {
-                output += `# ${k}: ${v}\n`;
+                output += `# ${this.sanitizeComment(k, delimiter)}: ${this.sanitizeComment(String(v), delimiter)}\n`;
             }
         }
         return output ? output + '\n' : '';

package/dist/generators/EpubGenerator.d.ts

@@ -0,0 +1,18 @@
+import { ConversionResult, GeneratorConfig, OfficeParserAST } from '../types.js';
+import { BaseGenerator } from './BaseGenerator.js';
+/**
+ * Generates a minimal, valid EPUB 3 file from an AST.
+ *
+ * Every AST node is rendered as a single XHTML content document (reusing `HtmlGenerator`
+ * for the actual markup, since EPUB content documents are XHTML) and packaged with the
+ * required `mimetype`, `META-INF/container.xml`, OPF manifest, and navigation document.
+ *
+ * `HtmlGenerator` embeds images as base64 `data:` URIs, but EPUB reading systems do not
+ * render `data:` URIs - images must be packaged as separate resources referenced by a
+ * relative path. So each data-URI image is extracted into `OEBPS/images/`, declared in
+ * the manifest, and its `<img src>` rewritten to point at the packaged file.
+ */
+export declare class EpubGenerator extends BaseGenerator<'epub'> {
+    constructor(ast: OfficeParserAST, config?: GeneratorConfig<'epub'>);
+    generate(): Promise<ConversionResult<'epub'>>;
+}